// Copyright 2017 The PDFium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Original code copyright 2014 Foxit Software Inc. http://www.foxitsoftware.com

#ifndef CORE_FPDFAPI_PARSER_CPDF_FLATEENCODER_H_
#define CORE_FPDFAPI_PARSER_CPDF_FLATEENCODER_H_

#include <stdint.h>

#include "core/fxcrt/data_vector.h"
#include "core/fxcrt/raw_span.h"
#include "core/fxcrt/retain_ptr.h"
#include "core/fxcrt/span.h"
#include "third_party/abseil-cpp/absl/types/variant.h"

class CPDF_Dictionary;
class CPDF_Encryptor;
class CPDF_Stream;
class CPDF_StreamAcc;
class IFX_ArchiveStream;

class CPDF_FlateEncoder {
 public:
  CPDF_FlateEncoder(RetainPtr<const CPDF_Stream> pStream, bool bFlateEncode);
  ~CPDF_FlateEncoder();

  void UpdateLength(size_t size);
  bool WriteDictTo(IFX_ArchiveStream* archive,
                   const CPDF_Encryptor* encryptor) const;

  pdfium::span<const uint8_t> GetSpan() const;

 private:
  bool is_owned() const {
    return absl::holds_alternative<DataVector<uint8_t>>(m_Data);
  }

  // Returns |m_pClonedDict| if it is valid. Otherwise returns |m_pDict|.
  const CPDF_Dictionary* GetDict() const;

  // Must outlive `m_Data`.
  RetainPtr<CPDF_StreamAcc> const m_pAcc;

  absl::variant<pdfium::raw_span<const uint8_t>, DataVector<uint8_t>> m_Data;

  // Only one of these two pointers is valid at any time.
  RetainPtr<const CPDF_Dictionary> m_pDict;
  RetainPtr<CPDF_Dictionary> m_pClonedDict;
};

#endif  // CORE_FPDFAPI_PARSER_CPDF_FLATEENCODER_H_
`CPDF_FlateEncoder` 类提供了一组接口功能用于处理 PDF 数据流中的 Flate 编码。以下是该接口的功能列表：

### 构造与析构函数
1. * *CPDF_FlateEncoder(RetainPtr<const CPDF_Stream> pStream, bool bFlateEncode) * *: 构造函数，用于初始化 Flate 编码器。
2. * *~CPDF_FlateEncoder() * *: 析构函数。

### 公共方法
3. * *void UpdateLength(size_t size) * *: 更新流的长度信息。
4. * *bool WriteDictTo(IFX_ArchiveStream * archive, const CPDF_Encryptor * encryptor) const** : 将字典写入到指定的档案流中。
5. * *pdfium::span<const uint8_t> GetSpan() const** : 获取编码数据的 span。

### 私有方法和属性
6. * *bool is_owned() const** : 检查编码数据是否由该对象拥有。
7. * *const CPDF_Dictionary * GetDict() const** : 获取当前有效的字典对象。

### 成员变量
- **RetainPtr<CPDF_StreamAcc> const m_pAcc * *: 保存原始流访问对象。
- **absl::variant<pdfium::raw_span<const uint8_t>, DataVector<uint8_t>> m_Data** : 保存编码后的数据，可能是一个 span 或一个数据向量。
- **RetainPtr<const CPDF_Dictionary> m_pDict * *: 原始字典对象。
- **RetainPtr<CPDF_Dictionary> m_pClonedDict * *: 克隆的字典对象，当需要修改字典时使用。

这些功能构成了 `CPDF_FlateEncoder` 类的接口，主要用于对 PDF 流进行 Flate 压缩编码以及处理相关的字典和数据。